Setting up Kerberos Authentication For ITRS SSO

Introduction to Kerberos

Kerberos is an open source authentication mechanism. It has been described as “an authentication protocol for trusted hosts on untrusted networks” and has been the preferred authentication mechanism used by Microsoft operating systems from Windows 2000 onwards.

It has the following useful features:

Single sign-on: once a user has been authenticated once (for instance by logging into a Windows domain), they do not have to do so again, even when accessing services on other computers.
The user’s password never travels over the network, is never stored at all on the client machine and is not stored in unencrypted form even in the authentication server database.
None of the information in the messages exchanged can be re-used to impersonate the user. (This is not true for the older Microsoft authentication mechanism, NTLM)

Kerberos works by clients requesting “tickets” from a Key Distribution Center (KDC), which is associated with an authentication service. First a client (for example, Windows running on a workstation) gets a “ticket granting ticket” (TGT) from the KDC. The Kerberos protocol allows the user to prove their identity to the authentication service and the TGT is proof that this has happened.

When a client (such as a browser) needs access to a service (such as a database or a webserver) which uses Kerberos authentication, it needs to present a ticket for that service to the server in question. To get this ticket, the client sends a request to the KDC, specifying which service it the ticket will be for and providing secret information from its TGT which proves the identity of the user.

The service ticket is encrypted using a secret shared by the KDC and the service; if the server can read the ticket, it is assured that it proves the identity of the user. If the client presents a ticket for the wrong service, the server will report that it cannot read the ticket, and not that it is invalid.

The klist command

The klist command, available on both Windows and Unix, shows what tickets have been granted to the current user:

$ klist

Current LogonId is 0:0x51fe5

Cached Tickets: (7)

#0>    	Client: jdoe @ EMEA.ITRS
		Server: krbtgt/EMEA.ITRS @ EMEA.ITRS
		KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
		Ticket Flags 0x40e00000 -> forwardable renewable initial pre_authent
		Start Time: 3/14/2018 8:45:13 (local)
		End Time:   3/14/2018 18:45:13 (local)
		Renew Time: 3/21/2018 8:45:13 (local)
		Session Key Type: RSADSI RC4-HMAC(NT)
		Cache Flags: 0x1 -> PRIMARY
		Kdc Called: corsvr01.emea.itrs

#1>     	Client: jdoe @ EMEA.ITRS
		Server: HTTP/mwserver.emea.itrs @ EMEA.ITRS
		KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
		Ticket Flags 0x40a00000 -> forwardable renewable pre_authent
		Start Time: 3/14/2018 8:50:50 (local)
		End Time:   3/14/2018 18:45:13 (local)
		Renew Time: 3/21/2018 8:45:13 (local)
		Session Key Type: RSADSI RC4-HMAC(NT)
		Cache Flags: 0
		Kdc Called: corsvr01.emea.itrs

#2>  		Client: jdoe @ EMEA.ITRS
		Server: cifs/nas01.emea.itrs @ EMEA.ITRS
		KerbTicket Encryption Type: RSADSI RC4-HMAC(NT)
		Ticket Flags 0x40a00000 -> forwardable renewable pre_authent
		Start Time: 3/14/2018 8:46:21 (local)
		End Time:   3/14/2018 18:45:13 (local)
		Renew Time: 3/21/2018 8:45:13 (local)
		Session Key Type: RSADSI RC4-HMAC(NT)
		Cache Flags: 0
		Kdc Called: corsvr01.emea.itrs

The example above shows three tickets (out of a total of seven in the current Windows session): the Kerberos ticket-granting ticket, a ticket for a web service (which happens to be an instance of the ITRS SSO Agent) and a ticket for a CIFS service (a NAS file server).

The Server: line in each ticket shows the Kerberos “service principal name” for which the ticket was requested. It consists of a component identifying the type of service (krbtgt, HTTP or cifs) and another component which (in each case except the first) is the fully qualified domain name (FQDN) of the machine providing the service.

Summary

It is important to note from the overview above that:

Each service using Kerberos to authenticate its users needs an account in the Kerberos domain.
Client applications need to know the correct Kerberos Service Principal Name for the service in order to request a ticket.
All service tickets granted to a user will use the identity encoded in the initial ticket-granting ticket: when using Kerberos authentication on Windows, a user can only connect to a service using the identity with which they have logged on to Windows.

ITRS Single Sign On (SSO) overview

ITRS Single Sign On is a mechanism which uses JSON Web Tokens and asymmetric (public key) cryptography to authorise and authenticate users to ITRS components such as Geneos Gateways, Webslinger instances and Web Dashboards.

Tokens are issued by the ITRS SSO Agent and signed by it using a private key. The ITRS components use the corresponding public key to check the signature, which proves that the ticket has been issued by the agent and that its contents have not been altered.

Responsibilities of the SSO Agent

The ITRS SSO Agent is implemented as a web service. It is responsible for verifying the identity of the user (authentication) and for finding out what roles the user has been granted (authorisation).

For the authorisation part, the agent uses LDAP: once it has authenticated a user, it queries an LDAP server to find out what groups the user is a member of. ITRS components treat the names of LDAP groups as the names of roles to which the user has access.

For the authentication part, the agent supports HTTP “Basic” authentication as well as Kerberos. This is mainly useful for checking the operation of the authorisation part: it is much easier to switch between test users with different roles using basic authentication than using Kerberos.

Other ITRS components

ITRS components obtain tokens from the agent in various ways:

Active Console 2 uses an embedded HTTP client to connect to the agent’s authentication endpoint. It presents the token it obtains to the Gateway to authorize the user.
Webslinger and Web Dashboard use HTTP redirection to instruct the user’s web browser to visit special endpoints provide by the agent.
Gateway can redirect a REST client to the agent’s authentication endpoint to obtain a token that can be used to authorize REST requests.

Because the result of the authentication and authorisation process is encoded in a JSON web token, there is no need for the other ITRS components to know which mechanisms have been used.

Enable Kerberos for the SSO Agent

For the SSO Agent to authenticate users using Kerberos, all of the following must be true:

The agent must be running and the host it is running on must have a name which is known to the client machines.
The agent must be able to authenticate itself with the Kerberos controller
The agent’s Kerberos service principal name must be associated with the credentials used by the agent

The following sections expand on each of these points.

The Agent must be running

As noted above, the SSO Agent is a web service. It provides a /status endpoint which can be used to check that the agent is running and can be reached by browsers running on the client machines.

When Kerberos authentication is used, the fully qualified domain name (FQDN) of the machine where the agent is running will be used as part of the SPN.

For example, if the agent’s status page can be reached using the following URLs:

http://mwserver.emea.itrs:8083/status
http://mwserver:8083/status
http://192.168.10.221:8083/status

and assuming that mwserver.emea.itrs is the DNS reverse resolution of 192.168.10.221, then mwserver.emea.itrs is the FQDN, the name known to the client machines, for the agent’s host.

This can be checked before attempting to configure Kerberos for the agent.

The agent must be able to authenticate itself with the KDC

To authenticate with the KDC, the agent needs to be configured with credentials (username and password) with which to log on.

In most cases, the same credentials can be used to connect to the LDAP controller (for authorisation queries) and the KDC, because the LDAP controller and the KDC are usually the same domain controller and will certainly be in the same trust domain.

The SSO Agent documentation explains how to set the LDAP user name and password and how to set a separate Kerberos user name and password if required.

The agent also needs to know the location of the KDC. It can usually determine this by looking up a DNS record for the Kerberos service:

$ dig +noall +answer srv _kerberos._tcp.emea.itrs
_kerberos._tcp.emea.itrs. 600	IN	SRV	0 100 88 srv01.emea.itrs.
_kerberos._tcp.emea.itrs. 600	IN	SRV	0 100 88 corsvr01.emea.itrs.

The Java GSSAPI module used by the agent can also be configured using the krb5.conf file, as described in the SSO Agent documentation.

The Agent’s Kerberos service principal name must be set up correctly

As explained in the Kerberos overview above, clients using Kerberos authentication for the SSO Agent request a service ticket from the KDC using a name, called a Service Principal Name (or SPN), which they construct as follows:

Because the agent provides a web service, the first component Is HTTP/. This is the case whether the ordinary (http://) or secure (https://) protocol is used. This component is in upper case and includes no colon and only one slash.
The remainder of the name is the fully qualified domain name of the host where the agent is running. That is, it is the host name part of the agent’s /status URL. Note that it does not include the port.

So, if the agent’s /status URL is http://mwserver.emea.itrs:8083/status, its SPN is normally HTTP/mwserver.emea.itrs. However, if the hostname part of the URL is a name which is mapped to the actual host name of the agent by a CNAME (“canonical name lookup”) DNS record, then the SPN will contain the actual host name, not the name that appears in the URL.

If the Kerberos service is provided by Active Directory, then the agent’s SPN needs to be associated with the user name the agent uses to connect to Kerberos.

The following setspn command is used to do this:

setspn -S agent-SPN agent-username

For example, if the SPN used for the agent is HTTP/mwserver.emea.itrs and its user name is itrs_sso, then the command to issue would be:

setspn -S HTTP/mwserver.emea.itrs itrs_sso

The -S option shown ensures that no other user name has been associated with the SPN.

Troubleshooting

Scenario	Recommended action
Clients fail to authenticate in ITRS applications.	Check application logs. Check whether `/testuser` endpoint works. If `/testuser` endpoint works, check that user has LDAP groups expected by applications.
Browser falls to authenticate using `/testuser` endpoint.	Check that `/status` page is available. Check SSO Agent console output and log.
Status page is not available.	Check the SSO Agent is running. Check firewall.
SSO Agent reports error reading Kerberos message	Check that the SSO Agent is using correct credentials to connect to Kerberos.
SSO Agent log reports that client is attempting NTLM authentication. Error message in the form `ERROR com.itrsgroup.ssoagent.authentication - Client is attempting NTLM authentication. There is a configuration issue.`	Check that the SSO Agent's SPN is set up correctly. Check that CNAME records do not cause host name in SPN to be different from URL.
SSO Agent log reports that it cannot verify Kerberos credential because realm is not as expected. Warning message in the form `WARNING com.itrsgroup.ssoagent.authentication - Cannot verify Kerberos credential: realm='xxx', expected='yyy'`	Consider changing `kerberos.realm_mismatch` setting. See Disable the realm-checking feature.